Skip to main content

PX4 SITL

Using the Gazebo​

First, we will build a simulated target using the console environment. This will allow us to verify the system setup before committing to the real hardware and IDE.

Navigate to the PX4-Autopilot directory and start Gazebo SITL using the following command:

make px4_sitl gz_x500

If you have Gazebo Classic installed, start Gazebo Classic SITL using the following command:

make px4_sitl gazebo-classic

This will open the PX4 console:

PX4 console

Enter the following command to make the drone fly (as shown in the console above):

pxh> commander takeoff

The vehicle will take off and you will see the following in the Gazebo simulator UI:

Gazebo UI and aircraft takeoff

The drone can be landed by typing, and the entire simulation can be stopped by pressing CTRL+C (or typing shutdown) commander land.

Using a ground control station for simulated flight is closer to actual aircraft operation. While the aircraft is flying (in takeoff flight mode), click a location on the map and enable the slider. This will reposition the aircraft.

QGroundControl Go

SITL important concepts​

In the process of using Gazebo for Software-In-The-Loop (SITL) simulation in PX4, GZ_VERSION, px4_gz_bridge,, ros_gz_bridge and SDF are the four core concepts corresponding to version management, cross-module communication, and simulation model definition, respectively. The following is a detailed analysis:

1. PX4 Gazebo Version GZ_VERSION​

GZ_VERSION This is an environment variable used to specify the Gazebo version in the PX4 build system . Its core function is to solve the "PX4 and Gazebo version compatibility" problem - different PX4 versions support different Gazebo versions. You need to use this variable to clearly compile the target version to avoid compilation failures or functional abnormalities.

1. Core Background: Gazebo Version Evolution and PX4​

Gazebo (now part of Open Robotics) has gone through several major version iterations, and PX4 supports it with a clear "version binding" feature, mainly divided into two series:

  • Gazebo Classic: such as Gazebo 9 and 11 (mainly supported versions of PX4 v1.13 and earlier);
  • Gazebo Fortress/Edifice (next generation Gazebo): Gradually migrated from PX4 v1.14 and now mainstream (naming changed from "Gazebo X" to "GZ-XXX", such as GZ-Fortress corresponds to version 12).

2. GZ_VERSION Values and usage​

GZ_VERSION ValueCorresponding Gazebo versionPX4 Supported Version RangeCore Purpose
9 / 11Gazebo Classic 9/11PX4 v1.13 and earlierTraditional SITL simulation (such as multi-rotor and fixed-wing basic scenarios)
fortressGZ-Fortress（v12）PX4 v1.14 ~ v1.15Next-generation simulation, supporting more complex physical effects
edificeGZ-Edifice（v11）PX4 v1.14+ (optional)Transitional version, compatible with some scenarios
harmonicGZ-Harmonic（v13）PX4 v1.16+ (latest mainstream)Latest version, optimized performance and multi-robot support

3. How to GZ_VERSION​

When compiling PX4 SITL, specify the version through the terminal environment variable, as shown below:

# 1. 临时设置（当前终端生效）：指定使用GZ-Fortress
export GZ_VERSION=fortress

# 2. 编译PX4 SITL（以多旋翼为例）
make px4_sitl gz_x500

2. px4_gz_bridgeCore communication​

px4_gz_bridge It is a dedicated communication interface library officially developed by PX4 . It is used to realize "bidirectional data transmission" between PX4 flight controller (SITL mode) and Gazebo simulator, and is the "data hub" of SITL simulation.

1. Core Function:​

PX4 (flight control logic) and Gazebo (physical simulation) are based on different message protocols. px4_gz_bridge Their core functions are protocol conversion and data routing. The main interactive data types include:

Data directionKey data typesUsage
PX4 → Gazebo (control instructions)Motor speed command (Motor Command), attitude control commandPX4 sends "control signals" to Gazebo to drive the simulated drone's movements
Gazebo → PX4 (sensor data)IMU (Inertial Measurement Unit), GPS, barometer, visual odometryGazebo feeds back "sensor data in the simulation environment" to PX4 for the flight control to calculate position/attitude

2. Technical Features: Lightweight, Native​

  • No additional dependencies: directly integrated into the PX4 source code src/modules/px4_gz_bridge/ directory, automatically built with PX4 compilation, no need to install separately;
  • Version binding: px4_gz_bridge The code will be GZ_VERSION adapted to ensure compatibility with the specified Gazebo version (such as message format optimization for GZ-Fortress);
  • Extensible: Supports custom message types (such as adding specific sensor data) by simply adding the corresponding protocol conversion logic in the bridge code.

3. ros_gz_bridgeCommunication bridge between ROS and Gazebo (indirectly supports PX4​

ros_gz_bridge It is a universal communication bridge between ROS (Robot Operating System) and Gazebo. It is not exclusive to PX4, but it is a key middleware in the composite scenario of "PX4+ROS+Gazebo" (such as when ROS nodes are required to process perception and planning algorithms).

1. px4_gz_bridge The core​

Many beginners confuse the two, and need to clarify their positioning differences:

Comparison Dimensionpx4_gz_bridgeros_gz_bridge
Both communicationPX4 flight control ↔ GazeboROS node ↔ Gazebo
Protocol BasicsPX4 custom UORB message ↔ Gazebo messageROS message (e.g. sensor_msgs/Imu) ↔ Gazebo message
Belonging and dependencePX4 source code built-in, no ROS dependencyMaintained by Open Robotics, requires ROS 2 (such as Humble)
PX4 scenario usageBasic SITL is required (it also needs to be started when there is no ROS)Used when ROS functionality is required (such as RViz visualization, ROS planning nodes)

2. Typical​

When you need to use ROS to process data (such as using ROS 2 nodes for target detection and path planning), ros_gz_bridge you need to px4_gz_bridge work with it. The data flow example is:

Gazebo（仿真传感器）→ ros_gz_bridge → ROS 2节点（处理数据）→ ROS 2→PX4（如通过MAVLink）→ PX4飞控

Example startup command (ROS 2 Humble + GZ-Fortress):

4. SDF: "Blueprint"​

SDF (Simulation Description Format) is a standard XML file used by Gazebo to define simulation environments and models. In PX4 SITL, the appearance, physical properties, and sensor configuration of a drone are all defined through SDF files.

1. Core role: defining the “simulated world​

When PX4 SITL is started, Gazebo will load the corresponding SDF file, which contains two key pieces of information:

  • Drone model: such as the multi-rotor frame size, motor position, sensor (IMU/GPS) installation position, and physical parameters (mass, moment of inertia);
  • Simulation scene (World): such as ground, sky, wind, lighting and other environmental parameters (some scenes also include obstacles and other drones).

2. Location and​

The PX4 source code has pre-installed SDF files for commonly used drones. The paths are:

PX4-Autopilot/Tools/simulation/gz/models/
# 示例：X500多旋翼模型
PX4-Autopilot/Tools/simulation/gz/models/x500/x500.sdf

SDF file snippet (defining the IMU sensor):

<sensor name="imu" type="imu">
  <pose>0 0 0.05 0 0 0</pose> <!-- IMU在机架上的安装位姿（x,y,z,滚转,俯仰,偏航） -->
  <topic>/imu</topic> <!-- 传感器数据发布到Gazebo的话题 -->
  <imu>
    <angular_velocity>
      <noise type="gaussian">
        <mean>0.0</mean>
        <stddev>0.001 0.001 0.001</stddev> <!-- 角速度噪声参数 -->
      </noise>
    </angular_velocity>
    <!-- 加速度计、陀螺仪等参数省略 -->
  </imu>
</sensor>

3. Key Features: Customizability and​

  • Parameter modification: You can directly edit the SDF file to adjust simulation parameters (such as increasing sensor noise and modifying the rack mass) without modifying the PX4 core code;
  • Model reuse: Supports importing third-party SDF models (such as custom drones and scenes). Simply put the model file into Gazebo's model search path (or specify the path in the PX4 startup script).

Summary: The synergistic​

In the PX4 Gazebo SITL flow, the collaborative logic of the four concepts can be summarized as follows:

  1. GZ_VERSION Ensure compatibility by specifying the target Gazebo version;
  2. Gazebo loads the SDF file and builds the simulation world including the drone and the environment;
  3. px4_gz_bridge Start and implement core data interaction between the PX4 flight controller and Gazebo (control commands + sensor data);
  4. If ROS functionality is required, ros_gz_bridge start it and forward Gazebo data to the ROS topic (or receive ROS commands), forming a "PX4-ROS-Gazebo" closed loop.

Understanding the roles of these four is the basis for troubleshooting PX4 SITL compilation errors and customizing simulation scenarios (such as solving common problems such as "no sensor data feedback" and "Gazebo startup failure").

Frequently Asked​

1. Make px4_sitl gz_x500 shows Preflight Fail. Preflight check failed and sensor data​

Solution 1: Uninstall and reinstall the gz version, such as gzgarden gzharmonic, etc. https://github.com/PX4/PX4-Autopilot/issues/24033 https://discuss.px4.io/t/px4-simulation-in-gazebo-fortress-support/45249 Solution 2: Since the gz file of Tools was replaced with the gz file of v1.16 in version v1.15, there is no problem when replacing it back to the original version. Solution 3: Use other simulation body and environment models, such as make px4_sitl gz_x500 Solution 4: Check whether the sdf file contains the sensor plug-in. If not, try Missing sensors for a Gazebo simulation

2. ros_gz_bridge does not work, and cannot use rviz2 to obtain PX4 x500_mono_cam image​

https://discuss.px4.io/t/ros-gz-bridge-not-working-unable-to-use-rviz2-to-fetch-px4-x500-mono-cam-image-topic/44447

3. Timestamp synchronization and alignment​

https://blog.csdn.net/2401_83038233/article/details/149101727